CIGI Lab Jupyter Notebook Style Guide: Template Notebook

This Notebook is a template for creating new Jupyter Notebooks according to the CIGI Lab style. This notebook is a companion to the CIGI Lab – Public-Facing Jupyter Notebook Checklist and Style Guide, which can be found at https://drive.google.com/file/d/1EJ_pSjX2IiNv8K8heGOLsXGHUxIIclrf/view?usp=sharing.

Notebook author: Rebecca Vandewalle
Notebook created: Feb 10, 2021. Last updated: Feb 12, 2021

Style notes for Notebook start: Include author and creation/update date on separate lines for better visibility

Notebook Outline:

  1. Introduction
  2. Descriptive Text
    1. Figures
    2. Tables
    3. Markdown vs. Html
  3. Working with Code Cells
  4. References

Style notes for Table of Contents: Use autonumbering (ex. 1. 1. 1. and let Markdown number sections), and keep anchor ids to section topics rather than section order (ex. 'figs' rather than sect_1a). This will help if you decide to restructure the Notebook.

Introduction

This is a good spot to introduce the topic of the notebook and the problem. Should be a general overview but more detailed than the summary at the beginning of the notebook.

Descriptive Text

You can have multiple paragraphs in a cell or have one cell per paragraph depending on how you prefer to organize your text.

Here is one way to add footnotes or references. 1

Figures

Local and remote images can be added. Preferably store local images in an "img" folder. You can add images in Markdown, but <img> tags can be easier to work with.

This is an easy way to include an image using Markdown.

This is a cat

Figure 1: An image of a cat, image created using Markdown

Setting image properties such as width and float behavior is easier using html.

Figure 2: An image of a cat, image created using html <img> tag

Tables

Tables can be created using Markdown, HTML, or from code output. Some examples follow. Tables should be described in the descriptive text and should include a table caption where relevant.

This is an example of a straightforward Markdown table.

Col 1 Col 2 Col 3
2 4.5 6
0 1.98 10

Table 1: An example table in Markdown

This is an example of a table using HTML.

Col 1Col 2Col 3
24.56
01.9810

Table 1: An example table in Markdown

Markdown vs. Html

Generally stick with Markdown if you will primarily be using simple formatting. If you are often using more complex formatting that needs Html, it is better if you use Html throughout the Notebook.

Working with Code Cells

New code should be written to conform to PEP8 style (https://www.python.org/dev/peps/pep-0008/). A useful PEP8 checker can be found here http://pep8online.com/ .

Introduce code before inserting a code cell. Comments are optional for one line of code that is discribed in the text, but are needed for any longer code blocks.

In [4]:
2+2
Out[4]:
4

The longer code block below should have a comment.

In [5]:
# this block does something

2+2
2+2
Out[5]:
4

After introducing and demonstrating the code, it is good to explain what it did and how this relatses to the notebook theme. If showing multiple examples, demonstrate how the code sections relate to each other.

References

Style notes for Table of Contents: Link to each reference within the notebook. If citing many references, consider having each reference in its own cell so the link works better.

Shaowen Wang (2010) A CyberGIS Framework for the Synthesis of Cyberinfrastructure, GIS, and Spatial Analysis, Annals of the Association of American Geographers, 100:3, 535-557, DOI: 10.1080/00045601003791243

In [ ]: